#ifndef __USM_CHARSET_H__
#define __USM_CHARSET_H__
/* Functions -------------------------------------------------------------- */
/**
    \fn JZ_Error_t USM_CS_Utf8len(const JZ_CHAR *pszString, JZ_INT32* pnLength)

    \brief Gets the length of a UTF-8 string.

    \param[in] pszString The UTF-8 string.
    \param[out] pnLength Pointer to store the length of the UTF-8 string on success.

    \retval JZ_SUCCESS Successful.
    \retval JZ_FAILURE Failed.
    \retval JZ_ERROR_BAD_PARAMETER Bad parameter passed.

    \remark
     * UNICODE -                           UTF-8
     *00000000 ~ 0000007F           0xxxxxxx
     *00000080 ~ 000007FF           110xxxxx 10xxxxxx
     *00000800 ~ 0000FFFF           1110xxxx 10xxxxxx 10xxxxxx
     *00010000 ~ 001FFFFF           11110xxx 10xxxxxx 10xxxxxx 10xxxxxx
     *00200000 ~ 03FFFFFF           111110xx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx
     *04000000 ~ 7FFFFFFF           1111110x 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx
*/
JZ_Error_t USM_CS_Utf8len(const JZ_CHAR *pszString, JZ_INT32* pnLength);


/**
    \fn JZ_Error_t USM_CS_Str2Unicode(JZ_WCHAR *pwszDest, const JZ_CHAR *pszSrc, USM_CS_Format_t format, JZ_INT32 nLength)

    \brief Converts a string into a unicode string.

    \param[out] pwszDest The destination wide-character string.
    \param[in] pszSrc The source string which charset format is \a format.
    \param[in] format The charset format.
    \param[in] nLength The length of the source string. The value of 0 represents the source string ends with a null character.

    \retval JZ_SUCCESS Successful.
    \retval JZ_FAILURE Failed.
    \retval JZ_ERROR_BAD_PARAMETER Bad parameter passed.

    \remark
*/
JZ_Error_t USM_CS_Str2Unicode(JZ_WCHAR *pwszDest, const JZ_CHAR *pszSrc, USM_CS_Format_t format, JZ_INT32 nLength);


/**
    \fn JZ_Error_t USM_CS_Unicode2Str(JZ_CHAR *pszDest, USM_CS_Format_t format, const JZ_WCHAR *pwszSrc, JZ_INT32 nLength)

    \brief Converts a Unicode string into a string encoded in the specified character set.

    \param[out] pszDest The destination string which charset format is \a format.
    \param[in] pwszSrc The source wide-character string.
    \param[in] format The charset format.
    \param[in] nLength The length of the source wide-character string. The value of 0 represents the source wide-character string ends with a null character.

    \retval JZ_SUCCESS Successful.
    \retval JZ_FAILURE Failed.
    \retval JZ_ERROR_BAD_PARAMETER Bad parameter passed.

    \remark

    \see USM_CS_Str2Unicode
*/
JZ_Error_t USM_CS_Unicode2Str(JZ_CHAR *pszDest, USM_CS_Format_t format, const JZ_WCHAR *pwszSrc, JZ_INT32 nLength);


/**
    \fn JZ_Error_t USM_CS_Utf82Unicode(JZ_WCHAR *pwszDest, const JZ_CHAR *pszSrc, JZ_INT32 nLength)

    \brief Converts a UTF-8 string into a Unicode string.

    \param[out] pwszDest The destination wide-character string.
    \param[in] pszSrc The source string which charset format is UTF-8.
    \param[in] nLength The length of the source string. The value of 0 represents the source string ends with a null character.

    \retval JZ_SUCCESS Successful.
    \retval JZ_FAILURE Failed.
    \retval JZ_ERROR_BAD_PARAMETER Bad parameter passed.

    \remark

    \see USM_CS_Unicode2Utf8
*/
JZ_Error_t USM_CS_Utf82Unicode(JZ_WCHAR *pwszDest, const JZ_CHAR *pszSrc, JZ_INT32 nLength);


/**
    \fn JZ_Error_t USM_CS_Unicode2Utf8(JZ_CHAR *pszDest, const JZ_WCHAR *pwszSrc, JZ_INT32 nLength)

    \brief Converts a Unicode string into a UTF-8 string.

    \param[out] pszDest The destination UTF-8 string.
    \param[in] pwszSrc The source wide-character string.
    \param[in] nLength The length of the source wide-character string. The value of 0 represents the source wide-character string ends with a null character.

    \retval JZ_SUCCESS Successful.
    \retval JZ_FAILURE Failed.
    \retval JZ_ERROR_BAD_PARAMETER Bad parameter passed.

    \remark

     * UNICODE -                           UTF-8
     *00000000 ~ 0000007F           0xxxxxxx
     *00000080 ~ 000007FF           110xxxxx 10xxxxxx
     *00000800 ~ 0000FFFF           1110xxxx 10xxxxxx 10xxxxxx
     *00010000 ~ 001FFFFF           11110xxx 10xxxxxx 10xxxxxx 10xxxxxx
     *00200000 ~ 03FFFFFF           111110xx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx
     *04000000 ~ 7FFFFFFF           1111110x 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx

    \see USM_CS_Utf82Unicode
*/
JZ_Error_t USM_CS_Unicode2Utf8(JZ_CHAR *pszDest, const JZ_WCHAR *pwszSrc, JZ_INT32 nLength);



/**
    \fn JZ_Error_t USM_CS_ISO2Unicode(JZ_WCHAR *pwszDest, const JZ_CHAR *pszSrc, USM_CS_Format_t format, JZ_INT32 nLength)

    \brief Converts an ISO 8859 encoded string into a Unicode string.

    \param[out] pwszDest The destination wide-character string.
    \param[in] pszSrc The source string which charset format is a member of the ISO 8859 family.
    \param[in] format The charset format in the ISO 8859 family.
    \param[in] nLength The length of the source string. The value of 0 represents the source string ends with a null character.

    \retval JZ_SUCCESS Successful.
    \retval JZ_FAILURE Failed.
    \retval JZ_ERROR_BAD_PARAMETER Bad parameter passed.

    \remark

    \see USM_CS_Unicode2ISO
*/
JZ_Error_t USM_CS_ISO2Unicode(JZ_WCHAR *pwszDest, const JZ_CHAR *pszSrc, USM_CS_Format_t format, JZ_INT32 nLength);


/**
    \fn JZ_Error_t USM_CS_Unicode2ISO(JZ_CHAR *pszDest, USM_CS_Format_t format, const JZ_WCHAR *pwszSrc, JZ_INT32 nLength)

    \brief Converts a Unicode string into an ISO 8859 encoded string.

    \param[out] pszDest The destination string which charset format is a member of the ISO 8859 family.
    \param[in] format The charset format in the ISO 8859 family.
    \param[in] pwszSrc The source wide-character string.
    \param[in] nLength The length of the source wide-character string. The value of 0 represents the source wide-character string ends with a null character.

    \retval JZ_SUCCESS Successful.
    \retval JZ_FAILURE Failed.
    \retval JZ_ERROR_BAD_PARAMETER Bad parameter passed.

    \remark

    \see USM_CS_ISO2Unicode
*/
JZ_Error_t USM_CS_Unicode2ISO(JZ_CHAR *pszDest, USM_CS_Format_t format, const JZ_WCHAR *pwszSrc, JZ_INT32 nLength);


/**
    \fn JZ_Error_t USM_CS_GetMatchedCode(JZ_UINT16 nMappingTable[][2], JZ_UINT16 nTableLen, JZ_UINT16 nCode, JZ_UINT16 *pnMatchedCode)
    \brief binary_search in 2D char-map array

    \param[in]  nMappingTable : a 2D character-map array.
    \param[in]  nTableLen : number of character-pair in table
    \param[in]  nCode : code of character to search in table
    \param[out]  pnMatchedCode : pointer to store the matched code if success.

    \retval JZ_SUCCESS Successful.
    \retval JZ_FAILURE Failed.
    \remark

*/
JZ_Error_t USM_CS_GetMatchedCode(JZ_UINT16 nMappingTable[][2], JZ_UINT16 nTableLen, JZ_UINT16 nCode, JZ_UINT16 *pnMatchedCode);

#endif
